This is Part I of a tutorial about the ColdBox config.xml This introduces you to the framework settings and what you can define and do in ColdBox. You can find a sample config.xml below. We will go section by section, explain what each section does, how you can use it, and maybe you can give me feedback on future versions. Also, you can find the schema documentation by using the link below: http://luismajano.com/projects/coldbox/documents/SchemaDocs/index.html A great place to start can also be found in the wiki: http://trac.luismajano.com/coldbox/wiki/cbConfigGuide mail.server.com myusername mypassword cfcoldbox@coldbox.com joe@coldbox.com luis@gmail.com dev localhost mydev Layout.Main.cfm vwEmails vwPhones vwContactBook includes/main en_US session We will start off with the Settings Element. This element is used to define the framework settings, you can look at the schema to see which settings are required and which ones are optional. As a rule of thumb, I always define all of them and if I do not use the setting, the value is blank. The first setting is AppName, this is just used for internal references and you can use it throughout your code using the getSetting("value",[false]) method. This method is used to retrieve keys from the internal structure that holds all of these settings. So you have all of your configuration settings on demand. You can also retrieve the framework settings by using the getSetting("value", [FromFrameworkBooleanFlag=true] ). This setting is required. The AppCFMXMapping is used to declare the path to follow for your application. This is how ColdBox can find out where your application resides and how to invoke it. You can use ColdFusion Mappings or just plain relative URL's from the web root. You can separate the directories either using CFMX style / or just plain . (periods). So for example on above I use: coldboxSamples/applications/Addressbook or coldboxSamples.applications.Addressbook and I have a coldfusion mapping named coldboxSamples. However, if I had no mapping, then ColdBox would start from the webroot: / and look for coldboxSamples/applications/Addressbook. So you have that flexibility. Another important note, is that you can leave this setting blank. This means that the entire web root is dedicated to this application. So the only runing application is a coldbox application. This setting is required. The DebugMode setting is used to declare wether your entire application will show the ColdBox debugging information. This is a boolean setting. You can also activate the ColdBox debug mode for a single session by using the url parameters. http://myapp.com/index.cfm?debugmode=true&debugpass=test However, you will need to pass the debugpass parameter which is defined in the DebguPass setting. You put the password that will be asked in order to go into debug mode and out. This setting is not required. The DumpVarActive is a pretty cool feature that you can enable or disable in the config.xml. You can use the DumpVar parameter in your url in order to well, dump variables at the end of the request. However, you can only use this feature if you are in the ColdBox debug mode. You can send a variable name, scope, etc. or even a comma delimited list of variables to dump. Example: http://myapp.com/index.cfm?dumpvar=application,myvariable,session ColdBox will dump the application scope, the myvariable variable, and the session scope. This setting is not required. The ColdfusionLogging setting is a boolean setting that tells the framework to log all types of errors and exceptions in the ColdFusion logging facilities using cflog. ColdBox will create a new log file named after the AppName setting value. In the next setting, we go a foot deeper into implicit invocations and arrive at the DefaultEvent Setting. This is where you declare your event handler and method combination that will be invoked as a first request. This follows the ColdBox lifecycle, look at diagrams, in which the first request to the application, where no event has been defined by either url or post, the framework will execute this event. That is why you can go to index.cfm and the default event will be fired. Remember that the value must be in event handler syntax that follows the following regular expression: ^eh[a-zA-Z]+.(dsp|do|on)[a-zA-Z]+ For a more in depth look at event handlers, look at the Documentation section. So basically you are declaring what event to fire when no event has been defined or its the user's first request. This setting is required. The RequestStartHandler is where you declare the event handler and method combination that will be invoked at the start of every user request. This simulates the Application.cfc onRequestStart method, but enclosed within the framework. You can use this for security, variable settings, etc. This setting is not required. The RequestEndHandler is where you declare the event handler and method combination that will be invoked at the end of every user request. This simulates the onRequestEnd method, but enclosed within the framework. This setting is not required. The ApplicationStartHandler simulates the onApplicationStart method. You can use this to setup your application variables, initial configurations, etc. The cool thing is that in order to fire it again, you can just call it from any event handler method or you can fire it by using the framework reinit action parameter. fwreinit=true http://myapp.com/index.cfm?fwreinit=1 This tells the framework, to reinitialize the framework and the application to first request status. It will reload the config.xml, resource bundles, etc, and start the application fresh. This is a great way to test and debug your apps. This setting is not required. The OwnerEmail setting is used to declare the email address that will be used to send email notifications from the framework. This setting is required. The EnableBugReports setting is a boolean flag that tells ColdBox whether to email bug reports to the emails declared in the BugTracerReports sections, or not. So if you do not want to send bug reports on every exception, then you set this flag to false. This setting is not required, the default is TRUE. The UDFLibraryFile is a cool setting where you can declare the path to a UDF template to load for usage in the views, layouts and event handlers. You can use relative path's to your applications root or ColdFusion mappings. So for example if I have my udf template called udf.cfm in my includes directory I would use: value="includes/udf.cfm" , if I have them in a mapping called: myudfs, then I would use: value="/myudfs/udf.cfm" This setting is not required. The CustomErrorTemplate is a setting that simulates the cferror tag, however, you have the full Exception information stored in a bean in the request collection. You put here the name of the template to display on all errors. Once in the template you can access the ExceptionBean by retrieving it from the request collection: myException = getValue("ExceptionBean"); Then you can use the bean's methods to display the exception information in any way you want. This setting is not required. The ExceptionHandler setting is used to define the event handler method combination that will take care of your exceptions. You can use this to filter out certain exceptions, relocate to certain events, log the errors, etc. Please note that if this setting is defined, then ColdBox will not automatically log the errors for you, you will have to do it yourself. How? Well, an ExceptionBean is placed in the request collection for you to determine what to do with the exception, the CustomErrorTemplate is for you to determine how to display the exception. Below is a sample exception handler: This setting is not required. //Grab Exception From the Request Collection var exceptionBean = getValue("ExceptionBean"); if ( exceptionBean.getType() eq "Framework.EventHandlerNotRegisteredException" or exceptionBean.getType() eq "Framework.EventSyntaxInvalidException" ){ getPlugin("messagebox").setMessage("warning","The page you requested does not exist"); //relocate to home setNextEvent("ehGeneral.dspHome"); } else{ //Log the error getPlugin("logger").logErrorWithBean(ExceptionBean); } The MessageboxStyleClass setting is used in conjunction to the messagebox plugin. This is a plugin that actually builds a visual representation of a message box for errors,warnings, and informational purposes. Since it is a visual component, you can skin it using this setting. You declare the css class, that will be loaded in your layouts or views, that the messagebox will use. If you want to see the code for the messagebox plugin, then go to: system/includes/messagebox.cfm This setting is not required. The HandlersIndexAutoReload is a developer tool to facilitate the developer from constantly using the fwreinit=1 action flag. When ColdBox initialized the application, it uses the cfcviewer plugin to actually introspect your handlers for metadata. It then creates an internal registry of handler and its methods. This way, only registered handlers can be called, and with the correct syntax for any operating system. However, when you are developing, you are constantly adding/removing/editing methods inside of the handlers or even adding new handlers. That is why you get the EventHandler Not registered exceptions. So use this flag to true, to reload the index on every request. This setting is not required. Default is FALSE The ConfigAutoReload setting is similar to the one above, in that it reloads the entire config.xml and the index. Again, if you have errors due to your config, then reload it by using the fwreinit=1 or set this flag to true for development. Remember that these two flags are for development only. This setting is not required. Default is FALSE This is the end of Part I of the tutorial, tomorrow we will cover the rest of the sections of this incredible file. Enjoy.